home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / grafik / converter / mpimage42 / docs / mpimage.doc
Encoding:
Text File  |  1996-07-16  |  9.3 KB  |  303 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. MPImage.library/FreeMPImage
  6. MPImage.library/LoadMPImage
  7. MPImage.library/MPImageErrorMessage
  8. MPImage.library/RescaleMPImage
  9. MPImage.library/SaveMPImageA
  10. MPImage.library/SetMPImageScreen
  11.  
  12.  
  13. MPImage.library/FreeMPImage                        MPImage.library/FreeMPImage
  14.  
  15.    NAME   
  16.   FreeMPImage -- Free an image loaded using LoadMPImage() (V3)
  17.  
  18.    SYNOPSIS
  19.   FreeMPImage( MPi )
  20.                      A0
  21.  
  22.   void FreeMPImage( struct MPImage * );
  23.  
  24.    FUNCTION
  25.   Frees all data associated loaded with an image using LoadMPImage().
  26.  
  27.    INPUTS
  28.   MPi - structure returned by LoadMPImage().
  29.  
  30.    RESULT
  31.   None.
  32.  
  33.    EXAMPLE
  34.  
  35.    NOTES
  36.  
  37.    BUGS
  38.  
  39.    SEE ALSO
  40.   LoadMPImage()
  41.  
  42. MPImage.library/LoadMPImage                        MPImage.library/LoadMPImage
  43.  
  44.    NAME   
  45.   LoadMPImage -- Load an image in various formats (V4)
  46.  
  47.    SYNOPSIS
  48.   MPi = LoadMPImage( filename,screen,Flags )
  49.   D0                       A0       A1     D0
  50.  
  51.   struct MPImage *LoadMPImage
  52.                   ( const char *,struct Screen *,ULONG);
  53.  
  54.    FUNCTION
  55.   Load an image in BitMap, EGSBitMap or RGB format.
  56.  
  57.    INPUTS
  58.   filename - name of file from which to load image
  59.            - -c or -cnumber for clipboard
  60.   screen   - screen on which BitMap is to be used. May be NULL.
  61.   Flags    - Flags to control image loading
  62.       Default is to remap to screen palette and return a bitmap in BitMap
  63.       Only way to free is to call FreeMPImage().
  64.  
  65.       MPIF_EGS         - Return E_EBitMap rather than BitMap. 
  66.           Overrides MPIF_RGB
  67.       MPIF_CLONEBITMAP - You are free to zero BitMap/EGS_BitMap before
  68.           calling FreeMPImage(). You must then call FreeBitMap() or 
  69.           E_DisposeBitMap() yourself. Ignored for MPIF_RGB/GREY. If screen
  70.           supplied then clone is screen depth deep if possible.
  71.       MPIF_NOREMAP     - Don't remap to the current screen colors. Ignored
  72.           for MPIF_EGS/RGB/GREY. Returns error if 24 bit input.
  73.       MPIF_RGB         - return Red, Green, Blue instead of BitMap.
  74.       MPIF_GREY        - return Red, Green, Blue instead of BitMap. If
  75.           image is greyscale then Red, Green and Blue will be the same
  76.           and GreyScale will be TRUE
  77.       MPIF_FORCEGREY   - As MPIF_GREY except input will always be remapped
  78.           to greyscale.
  79.  
  80.    RESULT
  81.   MPi - Pointer to an MPImage structure holding the image data.
  82.         NULL if an error occurs. Use MPImageErrorMessage() to get error.
  83.  
  84.    EXAMPLE
  85.  
  86.    NOTES
  87.   If file format is JPG and env/mpimage/djpeg is set (e.g. djpeg "%s" "%s")
  88.   and not loading a BitMap then djpeg is used.
  89.  
  90.   If file format is PNG and env/mpimage/pngtopnm is set
  91.   (e.g. pngtopnm "%s" >"%s") and not loading a BitMap then pngtopnm is used.
  92.  
  93.   Other fileformats are IBLM (depth 1 to 8 and 24, EHB, HAM6 and HAM8),
  94.   PBM (all types) and any picture datatype. With dctv.library(3) can also
  95.   load DCTV images.
  96.  
  97.    BUGS
  98.   Waits 20 seconds for djpeg/pngtopnm to start then aborts.
  99.   Fails to set an error message if failure loading from clipboard.
  100.   Can also fail to set an error message in other (unknown) circumstances.
  101.  
  102.    SEE ALSO
  103.   FreeMPImage(),MPImageErrorMessage,graphics.library/FreeBitMap(),
  104.   egs.library/E_DisposeBitMap(),MPImageErrorMessage().
  105.  
  106. MPImage.library/MPImageErrorMessage        MPImage.library/MPImageErrorMessage
  107.  
  108.    NAME   
  109.   MPImageErrorMessage -- Return the last error set by MPImage.library. (V3)
  110.  
  111.    SYNOPSIS
  112.   msg = MPImageErrorMessage()
  113.   D0
  114.  
  115.   char *MPImageErrorMessage( void );
  116.  
  117.    FUNCTION
  118.   Returns the last error message set by this opener of MPImage.library.
  119.  
  120.    INPUTS
  121.   None.
  122.  
  123.    RESULT
  124.   Formatted Error Message.
  125.  
  126.    EXAMPLE
  127.  
  128.    NOTES
  129.  
  130.    BUGS
  131.  
  132.    SEE ALSO
  133.  
  134. MPImage.library/RescaleMPImage                  MPImage.library/RescaleMPImage
  135.  
  136.    NAME   
  137.   RescaleMPImage -- Scales an image created by LoadMPImage() (V3)
  138.  
  139.    SYNOPSIS
  140.   error = RescaleMPImage(MPi, x, y)
  141.   D0                     A0   D0 D1
  142.  
  143.   BOOL RescaleMPImage(struct MPImage *, UWORD, UWORD);
  144.  
  145.    FUNCTION
  146.   Scales an Image loaded by LoadMPImage() to new width and height.
  147.  
  148.    INPUTS
  149.   MPi - Image loaded by LoadMPImage
  150.   x   - New width of image
  151.   y   - New height of image
  152.  
  153.    RESULT
  154.   error - 1 for success, 0 for failure.
  155.           Use MPImageErrorMessage() to get error.
  156.  
  157.    EXAMPLE
  158.  
  159.    NOTES
  160.   Rescaling of bitmaps is done using BitMapScale().
  161.   Other rescaling is done using custom code with smoothing.
  162.  
  163.   If this function fails then the MPImage is no longer usable and
  164.   FreeMPImage() should be called to free it.
  165.  
  166.    BUGS
  167.   Bitmaps may not scale smoothly.
  168.   The rescaling of EGS images is not efficent.
  169.  
  170.    SEE ALSO
  171.   LoadMPImage(),MPImageErrorMessage(),FreeMPImage(),
  172.   graphics.library/BitMapScale().
  173.  
  174. MPImage.library/SaveMPImageA                      MPImage.library/SaveMPImageA
  175.  
  176.    NAME   
  177.   SaveMPImageA -- Save an image in various formats. (V3)
  178.   SaveMPIMage -- Varargs version of SaveMPImageA (V3)
  179.  
  180.    SYNOPSIS
  181.   succ = SaveMPImageA( file,red,green,blue,width,height,taglist)
  182.   D0                   A0   A1  A2    A3   D0    D1     A5
  183.  
  184.   BOOL SaveMPImageA( UBYTE *,UBYTE *,UBYTE *,UBYTE *,
  185.                                    UWORD,UWORD,struct TagItem *);
  186.  
  187.   succ = SaveMPImage( file,red,green,blue,width,height,Tag1, ...)
  188.  
  189.   BOOL SaveMPImage( UBYTE *,UBYTE *,UBYTE *,UBYTE *,
  190.                                    UWORD,UWORD,ULONG,...);
  191.  
  192.    FUNCTION
  193.   Saves/displays an image held in chunky buffers.
  194.  
  195.    INPUTS
  196.   file    - filename to save file as. If NULL or "" then image is
  197.             displayed on a custom screen.
  198.   red     - red chunky input.
  199.   green   - green chunky input.
  200.   blue    - blue chunky input.
  201.   width   - width of chunky buffers
  202.   height  - height of chunky buffers.
  203.   taglist - pointer to TagItem array.
  204.  
  205.   Tags are:
  206.  
  207.   MPIS_MODE   - Data is ULONG CAMG of output IFF file/screen EHB and HAM
  208.                 will be added if required. If not supplied then
  209.                 MPIS_MODENAME will be used. If that is not supplied then
  210.                 a CAMG mode will be generated.
  211.   MPIS_MODENAME - Data is char * mode name of CAMG of output. Invalid
  212.                   names are ignored.
  213.   MPIS_FORMAT - Data is char * specifying output format.
  214.                 Default is MPI_BW16. Values are:
  215.                 MPI_BW16   - "BW16"   - 16 colour ILBM grey scale.
  216.                 MPI_BW256  - "BW256"  - 256 colour ILBM grey scale.
  217.                 MPI_HAM6   - "HAM6"   - HAM6 with fixed (internal) palette.
  218.                 MPI_HAM6P  - "HAM6P"  - HAM6 with generated or supplied
  219.                                         palette - see MPIS_PALETTE.
  220.                 MPI_HAM8   - "HAM8"   - HAM8 with fixed (internal) palette.
  221.                 MPI_HAM8P  - "HAM8P"  - HAM8 with generated or supplied
  222.                                         palette - see MPIS_PALETTE.
  223.                 MPI_ILBM24 - "ILBM24" - 24 bit ILBM.
  224.                 MPI_PPM    - "PPM"    - P6 (or P5 if red,green and blue are
  225.                                         the same).
  226.                 MPI_COLOUR - "COLOUR" - ILBM with generated or supplied
  227.                                         palette - see MPIS_PALETTE.
  228.                 MPI_EHB    - "EHB"    - EHB with generated or supplied
  229.                                         palette - see MPIS_PALETTE.
  230.                 MPI_JPEG   - "JPEG"   - JPEG see NOTES.
  231.                 MPI_PNM    - "PNG"    - PNG see NOTES.
  232.                 MPI_DCTV3  - "DCTV3"  - DCTV 3 bit plane format
  233.                 MPI_DCTV4  - "DCTV4"  - DCTV 4 bit plane format
  234.   MPIS_PALETTE - Data is char * name of ILBM to load palette from.
  235.   MPIS_COLOURS - Data is ULONG number of colours for MPI_COLOUR.
  236.                  Default is is number of colours in MPIS_PALETTE if
  237.                  supplied, otherwise 16. If greater than that from
  238.                  MPIS_PALETTE then ignored.
  239.   MPIS_12BIT   - Data is BOOL. If TRUE then use faster 12bit colour palette
  240.                  generating algorithm for MPI_COLOUR and MPI_EHB. Default
  241.                  is FALSE to use 18bit algorithm.
  242.  
  243.    RESULT
  244.   error - 1 for success, 0 for failure.
  245.           Use MPImageErrorMessage() to get error.
  246.  
  247.    EXAMPLE
  248.  
  249.    NOTES
  250.   If MPIS_FORMAT is BW16 or BW256 and red,green and blue are the same then
  251.   a more efficent algorithm is used.
  252.  
  253.   When displaying on screen click in the top left and press a key to exit.
  254.  
  255.   If file format is JPEG and env/mpimage/cjpeg is set (e.g. cjpeg "%s" "%s")
  256.   then cjpeg is used.
  257.  
  258.   If file format is PNG and env/mpimage/pnmtopng is set
  259.   (e.g. 'pnmtopng "%s" >"%s"') then pnmtopng is used.
  260.  
  261.    BUGS
  262.   Does not work for images > 1024 wide (except PPM/JPEG/PNG).
  263.   The palette file requires a body which is loaded and then discarded.
  264.  
  265.   Waits 20 seconds for cjpeg/pnmtopng to start then aborts. This check is
  266.   not fool proof and the PIPE:xxx can be left hanging.
  267.  
  268.    SEE ALSO
  269.   MPImageErrorMessage().
  270.  
  271. MPImage.library/SetMPImageScreen              MPImage.library/SetMPImageScreen
  272.  
  273.    NAME   
  274.   SetMPImageScreen -- Sets the Screen name for progress requesters (V3)
  275.  
  276.    SYNOPSIS
  277.   SetMPImageScreen(ScreenName,Flags)
  278.                    A0         D0
  279.  
  280.   void SetMPImageScreen(char *, ULONG);
  281.  
  282.    FUNCTION
  283.   Sets the Screen Name for progress requesters for this opener.
  284.  
  285.    INPUTS
  286.   ScreenName - Name of Public Screen, NULL for default
  287.   Flags      - 0 - Do not show progress requesters (default)
  288.              - MPIF_PROGRESS - Do show progress requesters
  289.                                (except for non remapped bitmaps).
  290.  
  291.    RESULT
  292.   None.
  293.  
  294.    EXAMPLE
  295.  
  296.    NOTES
  297.   ScreenName must remain valid while MPImage.library is open.
  298.  
  299.    BUGS
  300.  
  301.    SEE ALSO
  302.  
  303.